package com.studerb.service.interfaces;

import java.util.List;

import com.studerb.model.Server;
import com.studerb.nntp.NntpConnection;

/**
 * This is an interface for the connection pooling. Besides the methods of the interface, it is required by contract
 * that any implementation send out {@link com.studerb.events.ConnectionPoolEvent ConnectionPoolEvent} events when a new
 * connection is created, destroyed, etc.
 */
public interface IConnectionPoolService extends IService {
    /**
     * @param servers {@link com.studerb.model.Server}
     * @return first available NntpConnection based on any server not included in the list of passed servers. Blocks
     * when no connection available.
     */
    NntpConnection getAnotherConnection(List<Server> servers);

    /**
     * @param server {@link com.studerb.model.Server}
     * @return first available NntpConnection based on any server but the server passed. Blocks when no connection
     * available.
     */
    NntpConnection getAnotherConnection(Server server);

    /**
     * @return first available NntpConnection of any server - blocks when no connection available
     */
    NntpConnection getConnection() throws InterruptedException;

    /**
     * @param server {@link com.studerb.model.Server}
     * @return NntpConnection of specified server
     */
    NntpConnection getConnection(Server server) throws InterruptedException;

    /**
     * @return first available NntpConnection from the master server blocks when no connection available
     */
    NntpConnection getMasterConnection() throws InterruptedException;

    /**
     * @return number of active connections
     */
    int getNumActive();

    /**
     * @return number of idle (non-active) connections
     */
    int getNumIdle();

    /**
     * @param connection {@link com.studerb.nntp.NntpConnection NntpConnection} to return back to the pool. By contract,
     * all users of the pool must return the connections after using.
     */
    void returnConnection(NntpConnection connection);

    /**
     * Used by some services to report authentication exceptions to the connection pool - if we don't do this, the
     * connection pool may sit in a infinitie loop trying to connect to a server that has a bad user/password combo
     * @param server of error occuring with
     */
    void reportServerTransientError(Server server);
}
